<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>API: event  YAHOO.util.CustomEvent   (YUI Library)</title>
	<link rel="stylesheet" type="text/css" href="assets/api.css">
</head>

<body id="yahoo-com">
<div id="doc3" class="yui-t2">

	<div id="hd">
        <h1>Yahoo! UI Library</h1>
        <h3>Event Utility&nbsp; <span class="subtitle">2.2.2</span></h3>
        <p>
        <a href="./index.html">Yahoo! UI Library</a> 
            &gt; <a href="./module_event.html">event</a>
                 &gt; YAHOO.util.CustomEvent 
                
            </p>
	</div>

	<div id="bd">
		<div id="yui-main">
			<div class="yui-b">


                    <h2>
                        

                        
                        
                            Class <b>YAHOO.util.CustomEvent</b>
                        <span class="extends">
                        </span>

                        <span class="extends">
                        </span>
                        
                        </code>
                    </h2>
                    <!-- class tree goes here -->
                    
                
  

                    <div class="summary description">
                        The CustomEvent class lets you define events for your application
that can be subscribed to by one or more independent component.
                    </div>

                        <div class="section constructor details">
                        <h3><a name="constructor_detail">Constructor</a></h3>
                        <div class="content">
                            <div class="detail">
                                <strong>YAHOO.util.CustomEvent</strong>
                                <code>
                                    (
  
                                        
                                                
                                                type

                                                , 
                                                oScope

                                                , 
                                                silent

                                                , 
                                                signature
                                    )
                                </code>
                                <div class="description">
                                        <dl>
                                            <dt>Parameters:</dt>
                                                <dd>
                                                    <code>type
                                                    &lt;String&gt; 
                                                    </code>
                                                     The type of event, which is passed to the callback
when the event fires
                                                </dd>
                                                <dd>
                                                    <code>oScope
                                                    &lt;Object&gt; 
                                                    </code>
                                                     The context the event will fire from.  "this" will
refer to this object in the callback.  Default value: 
the window object.  The listener can override this.
                                                </dd>
                                                <dd>
                                                    <code>silent
                                                    &lt;boolean&gt; 
                                                    </code>
                                                     pass true to prevent the event from writing to
the debugsystem
                                                </dd>
                                                <dd>
                                                    <code>signature
                                                    &lt;int&gt; 
                                                    </code>
                                                     the signature that the custom event subscriber
will receive. YAHOO.util.CustomEvent.LIST or 
YAHOO.util.CustomEvent.FLAT.  The default is
YAHOO.util.CustomEvent.LIST.
                                                </dd>
                                        </dl>
                                    
                                    
                                </div>
                            </div>
                        </div>
                    </div>

                        <div class="section field details">
                            <h3><a name="field_detail">Properties</a></h3>
                            <div class="content">
                                    <h4><a name="scope">scope</a>
                                        <code>- object</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            The scope the the event will fire from by default.  Defaults to the window 
obj
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="signature">signature</a>
                                        <code>- int</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            Custom events support two styles of arguments provided to the event
subscribers.  
<ul>
<li>YAHOO.util.CustomEvent.LIST: 
<ul>
<li>param1: event name</li>
<li>param2: array of arguments sent to fire</li>
<li>param3: <optional> a custom object supplied by the subscriber</li>
</ul>
</li>
<li>YAHOO.util.CustomEvent.FLAT
<ul>
<li>param1: the first argument passed to fire.  If you need to
pass multiple parameters, use and array or object literal</li>
<li>param2: <optional> a custom object supplied by the subscriber</li>
</ul>
</li>
</ul>
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="silent">silent</a>
                                        <code>- boolean</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            By default all custom events are logged in the debug build, set silent
to true to disable debug outpu for this event.
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="subscribers">subscribers</a>
                                        <code>- Subscriber[]</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            The subscribers to this event
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="type">type</a>
                                        <code>- string</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            The type of event, returned to subscribers when the event fires
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="YAHOO.util.CustomEvent.FLAT">YAHOO.util.CustomEvent.FLAT</a>
                                        <code>- static int</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            Subscriber listener sigature constant.  The FLAT type returns two
parameters: the first argument passed to fire and the optional 
custom object
                                        </div>
                                    </div>
     
                                        


                                    <hr />
                                    <h4><a name="YAHOO.util.CustomEvent.LIST">YAHOO.util.CustomEvent.LIST</a>
                                        <code>- static int</code>
                                    </h4>
                                    <div class="detail">
                                        <div class="description">
                                            Subscriber listener sigature constant.  The LIST type returns three
parameters: the event type, the array of args passed to fire, and
the optional custom object
                                        </div>
                                    </div>
     
                                        


                                    <hr />


                            </div>
                        </div>


                        <div class="section method details">
                            <h3><a name="methodDetails">Methods</a></h3>
                            <div class="content">
                                    <h4>
                                        <a name="_delete">_delete</a></h4>
                                    <div class="detail">
                                        <code>
                                         private 
                                        
                                        
                                        void
                                            <strong>_delete</strong>
                                           (
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            
                                        </div>

                                        <div class="description">


                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        void
                                                    </code></dt>
                                                    <dd></dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                                    <h4>
                                        <a name="fire">fire</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                        boolean
                                            <strong>fire</strong>
                                           (
                                                
                                                        
                                                         arguments
                                                    
                                                
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            Notifies the subscribers.  The callback functions will be executed
from the scope specified when the event was created, and with the 
following parameters:
<ul>
<li>The type of event</li>
<li>All of the arguments fire() was executed with as an array</li>
<li>The custom object (if any) that was passed into the subscribe() 
method</li>
</ul>
                                        </div>

                                        <div class="description">

                                                <dl>
                                                    <dt>Parameters:</dt>
                                                        <dd>
                                                            <code>arguments &lt;Object*&gt;</code>
                                                             an arbitrary set of parameters to pass to 
the handler.
                                                        </dd>
                                                </dl>

                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        boolean
                                                    </code></dt>
                                                    <dd>false if one of the subscribers returned false, 
true otherwise</dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                                    <h4>
                                        <a name="subscribe">subscribe</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                        void
                                            <strong>subscribe</strong>
                                           (
                                                
                                                        
                                                         fn
                                                    
                                                
                                                        , 
                                                         obj
                                                    
                                                
                                                        , 
                                                         override
                                                    
                                                
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            Subscribes the caller to this event
                                        </div>

                                        <div class="description">

                                                <dl>
                                                    <dt>Parameters:</dt>
                                                        <dd>
                                                            <code>fn &lt;Function&gt;</code>
                                                                    The function to execute
                                                        </dd>
                                                        <dd>
                                                            <code>obj &lt;Object&gt;</code>
                                                                   An object to be passed along when the event 
fires
                                                        </dd>
                                                        <dd>
                                                            <code>override &lt;boolean|Object&gt;</code>
                                                             If true, the obj passed in becomes 
the execution scope of the listener.
if an object, that object becomes the
the execution scope.
                                                        </dd>
                                                </dl>

                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        void
                                                    </code></dt>
                                                    <dd></dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                                    <h4>
                                        <a name="toString">toString</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                        void
                                            <strong>toString</strong>
                                           (
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            
                                        </div>

                                        <div class="description">


                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        void
                                                    </code></dt>
                                                    <dd></dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                                    <h4>
                                        <a name="unsubscribe">unsubscribe</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                        boolean
                                            <strong>unsubscribe</strong>
                                           (
                                                
                                                        
                                                         fn
                                                    
                                                
                                                        , 
                                                         obj
                                                    
                                                
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            Unsubscribes subscribers.
                                        </div>

                                        <div class="description">

                                                <dl>
                                                    <dt>Parameters:</dt>
                                                        <dd>
                                                            <code>fn &lt;Function&gt;</code>
                                                              The subscribed function to remove, if not supplied
all will be removed
                                                        </dd>
                                                        <dd>
                                                            <code>obj &lt;Object&gt;</code>
                                                              The custom object passed to subscribe.  This is
optional, but if supplied will be used to
disambiguate multiple listeners that are the same
(e.g., you subscribe many object using a function
that lives on the prototype)
                                                        </dd>
                                                </dl>

                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        boolean
                                                    </code></dt>
                                                    <dd>True if the subscriber was found and detached.</dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                                    <h4>
                                        <a name="unsubscribeAll">unsubscribeAll</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                        int
                                            <strong>unsubscribeAll</strong>
                                           (
                                            )
                                        </code>
                                        
                                        <div class="description">
                                            Removes all listeners
                                        </div>

                                        <div class="description">


                                                <dl>
                                                    <dt>Returns:
                                                    <code>
                                                        int
                                                    </code></dt>
                                                    <dd>The number of listeners unsubscribed</dd>
                                                </dl>
             
                                        </div>

                                    </div>
                                    <hr />
                            </div>
                        </div>


                        <div class="section method details">
                            <h3><a name="methodDetails">Events</a></h3>
                            <div class="content">
                                    <h4>
                                        <a name="subscribeEvent">subscribeEvent</a></h4>
                                    <div class="detail">
                                        <code>
                                        
                                        
                                        
                                            <strong>subscribeEvent</strong>

                                            (
                                                
                                                        
                                                         fn
                                                    
                                                
                                                        , 
                                                         obj
                                                    
                                                
                                                        , 
                                                         override
                                                    
                                                
                                            )

                                        </code>
                                        
                                        <div class="description">
                                            Custom events provide a custom event that fires whenever there is
a new subscriber to the event.  This provides an opportunity to
handle the case where there is a non-repeating event that has
already fired has a new subscriber.
                                        </div>

                                        <div class="description">


                                                <dl>
                                                    <dt>Parameters:</dt>
                                                        <dd>
                                                            <code>fn &lt;Function&gt;</code>
                                                             The function to execute
                                                        </dd>
                                                        <dd>
                                                            <code>obj &lt;Object&gt;</code>
                                                             An object to be passed along when the event 
fires
                                                        </dd>
                                                        <dd>
                                                            <code>override &lt;boolean|Object&gt;</code>
                                                             If true, the obj passed in becomes 
the execution scope of the listener.
if an object, that object becomes the
the execution scope.
                                                        </dd>
                                                </dl>


                                        </div>

                                    </div>
                                    <hr />
                            </div>
                        </div>





			</div>
		</div>
		<div class="yui-b">
            <div class="nav">

                    <div class="module">
                        <h4>Modules</h4>
                        <ul class="content">

                                <li class=""><a href="module_animation.html">animation</a></li>

                                <li class=""><a href="module_autocomplete.html">autocomplete</a></li>

                                <li class=""><a href="module_button.html">button</a></li>

                                <li class=""><a href="module_calendar.html">calendar</a></li>

                                <li class=""><a href="module_connection.html">connection</a></li>

                                <li class=""><a href="module_container.html">container</a></li>

                                <li class=""><a href="module_datasource.html">datasource</a></li>

                                <li class=""><a href="module_datatable.html">datatable</a></li>

                                <li class=""><a href="module_dom.html">dom</a></li>

                                <li class=""><a href="module_dragdrop.html">dragdrop</a></li>

                                <li class=""><a href="module_element.html">element</a></li>

                                <li class="selected"><a href="module_event.html">event</a></li>

                                <li class=""><a href="module_history.html">history</a></li>

                                <li class=""><a href="module_logger.html">logger</a></li>

                                <li class=""><a href="module_menu.html">menu</a></li>

                                <li class=""><a href="module_slider.html">slider</a></li>

                                <li class=""><a href="module_tabview.html">tabview</a></li>

                                <li class=""><a href="module_treeview.html">treeview</a></li>

                                <li class=""><a href="module_yahoo.html">yahoo</a></li>
                        </ul>
                    </div>

                    <div class="module">
                        <h4>Classes</h4>
                        <ul class="content">
                                <li class="selected"><a href="YAHOO.util.CustomEvent.html">YAHOO.util.CustomEvent</a></li>
                                <li class=""><a href="YAHOO.util.Event.html">YAHOO.util.Event</a></li>
                                <li class=""><a href="YAHOO.util.EventProvider.html">YAHOO.util.EventProvider</a></li>
                                <li class=""><a href="YAHOO.util.Subscriber.html">YAHOO.util.Subscriber</a></li>
                        </ul>
                    </div>

                    <div class="module">
                        <h4>Files</h4>
                        <ul class="content">        
                                <li class=""><a href="CustomEvent.js.html">CustomEvent.js</a></li>
                                <li class=""><a href="Event.js.html">Event.js</a></li>
                                <li class=""><a href="EventProvider.js.html">EventProvider.js</a></li>
                        </ul>
                    </div>

                    <div class="module">
                        <h4>Properties</h4>
                        <ul class="content">        
                                <li><a href="#scope">scope</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#signature">signature</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#silent">silent</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#subscribers">subscribers</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#type">type</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#YAHOO.util.CustomEvent.FLAT">YAHOO.util.CustomEvent.FLAT</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                                <li><a href="#YAHOO.util.CustomEvent.LIST">YAHOO.util.CustomEvent.LIST</a>
                                        <!--<code>&lt;int&gt;</code>-->
                                </li>
                        </ul>
                    </div>

                    <div class="module">
                        <h4>Methods</h4>
                        <ul class="content">        
                                <li><!--<code>void</code>-->
                                <a href="#_delete">_delete</a>
                                </li>
                                <li><!--<code>boolean</code>-->
                                <a href="#fire">fire</a>
                                </li>
                                <li><!--<code>void</code>-->
                                <a href="#subscribe">subscribe</a>
                                </li>
                                <li><!--<code>void</code>-->
                                <a href="#toString">toString</a>
                                </li>
                                <li><!--<code>boolean</code>-->
                                <a href="#unsubscribe">unsubscribe</a>
                                </li>
                                <li><!--<code>int</code>-->
                                <a href="#unsubscribeAll">unsubscribeAll</a>
                                </li>
                        </ul>
                    </div>

                    <div class="module">
                        <h4>Events</h4>
                        <ul class="content">        
                                <li>
                                <a href="#subscribeEvent">subscribeEvent</a>
                                </li>
                        </ul>
                    </div>


            </div>
		</div>
	</div>
	<div id="ft">
        <hr />
        Copyright &copy; 2007 Yahoo! Inc. All rights reserved.
	</div>
</div>
</body>
</html>
